<!DOCTYPE html>
<html id="docs" lang="en" class="">
	<head>
	<meta charset="utf-8">
<title>Writing a New Topic - Kubernetes</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="shortcut icon" type="image/png" href="../../../../images/favicon.png">
<link rel="stylesheet" type="text/css" href="../../../../css/base_fonts.css">
<link rel="stylesheet" type="text/css" href="../../../../css/styles.css">
<link rel="stylesheet" type="text/css" href="https://code.jquery.com/ui/1.12.1/themes/smoothness/jquery-ui.css">
<link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/sweetalert/1.1.3/sweetalert.min.css">
<link rel="stylesheet" type="text/css" href="../../../../css/callouts.css">
<link rel="stylesheet" type="text/css" href="../../../../css/custom-jekyll/tags.css">




<meta name="description" content="Writing a New Topic" />
<meta property="og:description" content="Writing a New Topic" />

<meta property="og:url" content="https://kubernetes.io/docs/home/contribute/write-new-topic/" />
<meta property="og:title" content="Writing a New Topic - Kubernetes" />

<script
src="https://code.jquery.com/jquery-3.2.1.min.js"
integrity="sha256-hwg4gsxgFZhOsEEamdOYGBf13FyQuiTwlAQgxVSNgt4="
crossorigin="anonymous"></script>
<script
src="https://code.jquery.com/ui/1.12.1/jquery-ui.min.js"
integrity="sha256-VazP97ZCwtekAsvgPBSUwPFKdrwD3unUfSGVYrahUqU="
crossorigin="anonymous"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/sweetalert/1.1.3/sweetalert.min.js"></script>
<script src="../../../../js/script.js"></script>
<script src="../../../../js/custom-jekyll/tags.js"></script>


	</head>
	<body>
		<div id="cellophane" onclick="kub.toggleMenu()"></div>

<header>
    <a href="../../../../index.html" class="logo"></a>

    <div class="nav-buttons" data-auto-burger="primary">
        <ul class="global-nav">
            
            
            <li><a href="../../../home.1">Documentation</a></li>
            
            <li><a href="../../../../blog/index.html">Blog</a></li>
            
            <li><a href="../../../../partners/index.html">Partners</a></li>
            
            <li><a href="../../../../community/index.html">Community</a></li>
            
            <li><a href="../../../../case-studies/index.html">Case Studies</a></li>
            
            
             <li>
                <a href="index.html#">
                    English <span class="ui-icon ui-icon-carat-1-s"></span>
                </a>
                <ul>
                
                    <li><a href="../../../../zh/index.html">中文 Chinese</a></li>
                
                    <li><a href="../../../../ko/index.html">한국어 Korean</a></li>
                
                </ul>
            </li>
         
            <li>
                <a href="index.html#">
                    v1.11 <span class="ui-icon ui-icon-carat-1-s"></span>
                </a>
                <ul>
                
                    <li><a href="https://kubernetes.io">v1.12</a></li>
                
                    <li><a href="../../../../index.html">v1.11</a></li>
                
                    <li><a href="https://v1-10.docs.kubernetes.io">v1.10</a></li>
                
                    <li><a href="https://v1-9.docs.kubernetes.io">v1.9</a></li>
                
                </ul>
            </li>
        </ul>
        
        <a href="../../../tutorials/kubernetes-basics/index.html" class="button" id="tryKubernetes" data-auto-burger-exclude>Try Kubernetes</a>
        <button id="hamburger" onclick="kub.toggleMenu()" data-auto-burger-exclude><div></div></button>
    </div>

    <nav id="mainNav">
        <main data-auto-burger="primary">
        <div class="nav-box">
            <h3><a href="../../../tutorials/stateless-application/hello-minikube/index.html">Get Started</a></h3>
            <p>Ready to get your hands dirty? Build a simple Kubernetes cluster that runs "Hello World" for Node.js.</p>
        </div>
        <div class="nav-box">
            <h3><a href="../../../home.1">Documentation</a></h3>
            <p>Learn how to use Kubernetes with the use of walkthroughs, samples, and reference documentation. You can even <a href="../../../../editdocs/index.html" data-auto-burger-exclude>help contribute to the docs</a>!</p>
        </div>
        <div class="nav-box">
            <h3><a href="../../../../community/index.html">Community</a></h3>
            <p>If you need help, you can connect with other Kubernetes users and the Kubernetes authors, attend community events, and watch video presentations from around the web.</p>
        </div>
        <div class="nav-box">
            <h3><a href="../../../../blog/index.html">Blog</a></h3>
            <p>Read the latest news for Kubernetes and the containers space in general, and get technical how-tos hot off the presses.</p>
        </div>
        </main>
        <main data-auto-burger="primary">
        <div class="left">
            <h5 class="github-invite">Interested in hacking on the core Kubernetes code base?</h5>
            <a href="https://github.com/kubernetes/kubernetes" class="button" data-auto-burger-exclude>View On Github</a>
        </div>

        <div class="right">
            <h5 class="github-invite">Explore the community</h5>
            <div class="social">
                <a href="https://twitter.com/kubernetesio" class="twitter"><span>Twitter</span></a>
                <a href="https://github.com/kubernetes/kubernetes" class="github"><span>Github</span></a>
                <a href="http://slack.k8s.io/" class="slack"><span>Slack</span></a>
                <a href="http://stackoverflow.com/questions/tagged/kubernetes" class="stack-overflow"><span>Stack Overflow</span></a>
                <a href="https://discuss.kubernetes.io" class="mailing-list"><span>Forum</span></a>
                <a href="https://calendar.google.com/calendar/embed?src=nt2tcnbtbied3l6gi2h29slvc0%40group.calendar.google.com" class="calendar"><span>Events Calendar</span></a>
            </div>
        </div>
        <div class="clear" style="clear: both"></div>
        </main>
    </nav>
</header>

		
		
		<section id="hero" class="light-text no-sub">
			





<h1></h1>
<h5></h5>












<div id="vendorStrip" class="light-text">
	<ul>
		
		
		<li><a href="../../../home.1" class="YAH">DOCUMENTATION</a></li>
		
		
		<li><a href="../../../setup/index.html">SETUP</a></li>
		
		
		<li><a href="../../../concepts/index.html">CONCEPTS</a></li>
		
		
		<li><a href="../../../tasks/index.html">TASKS</a></li>
		
		
		<li><a href="../../../tutorials/index.html">TUTORIALS</a></li>
		
		
		<li><a href="../../../reference.1">REFERENCE</a></li>
		
	</ul>
	<div id="searchBox">
		<input type="text" id="search" placeholder="Search" onkeydown="if (event.keyCode==13) window.location.replace('/docs/search/?q=' + this.value)" autofocus="autofocus">
	</div>
</div>

		</section>
		
		
<section id="deprecationWarning">
  <main>
    <div class="content deprecation-warning">
      <h3>
        Documentation for Kubernetes v1.11 is no longer actively maintained. The version you are currently viewing is a static snapshot.
        For up-to-date documentation, see the <a href="https://kubernetes.io/docs/home/">latest</a> version.
      </h3>
    </div>
  </main>
</section>


		<section id="encyclopedia">
			
<div id="docsToc">
     <div class="pi-accordion">
    	
        
        
        
        
        
         
             
                 
                          
                          
                 
             
         
             
         
             
         
             
         
             
         
             
         
             
         
             
         
         
        
        <a class="item" data-title="Documentation" href="../../../home.1"></a>

	
	
		
		
	<div class="item" data-title="Contributing to the Kubernetes Docs">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Content Organization" href="../content-organization/index.html"></a>

		
	
		
		
<a class="item" data-title="Creating a Documentation Pull Request" href="../stage-documentation-changes/index.html"></a>

		
	
		
		
<a class="item" data-title="Custom Hugo Shortcodes" href="../includes.1"></a>

		
	
		
		
<a class="item" data-title="Documentation Style Guide" href="../style-guide.1"></a>

		
	
		
		
<a class="item" data-title="Generating Reference Documentation for Kubernetes Federation API" href="../generated-reference/federation-api/index.html"></a>

		
	
		
		
<a class="item" data-title="Generating Reference Documentation for kubectl Commands" href="../generated-reference/kubectl/index.html"></a>

		
	
		
		
<a class="item" data-title="Generating Reference Documentation for the Kubernetes API" href="../generated-reference/kubernetes-api/index.html"></a>

		
	
		
		
<a class="item" data-title="Generating Reference Pages for Kubernetes Components and Tools" href="../generated-reference/kubernetes-components/index.html"></a>

		
	
		
		
<a class="item" data-title="Localizing Kubernetes Documentation" href="../localization/index.html"></a>

		
	
		
		
<a class="item" data-title="Participating in SIG-DOCS" href="../participating/index.html"></a>

		
	
		
		
<a class="item" data-title="Reviewing Documentation Issues" href="../review-issues/index.html"></a>

		
	
		
		
<a class="item" data-title="Using Page Templates" href="../page-templates/index.html"></a>

		
	
		
		
<a class="item" data-title="Writing a Blog Post" href="../blog-post/index.html"></a>

		
	
		
		
<a class="item" data-title="Writing a New Topic" href="index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
<a class="item" data-title="Supported Versions of the Kubernetes Documentation" href="../../supported-doc-versions/index.html"></a>

		
	






     </div> 
    <button class="push-menu-close-button" onclick="kub.toggleToc()"></button>
</div> 

			<div id="docsContent">
				
<p><a href="../../../editdocs#docs/home/contribute/write-new-topic.md" id="editPageButton">Edit This Page</a></p>

<h1>Writing a New Topic</h1>




<p>This page shows how to create a new topic for the Kubernetes docs.</p>











<ul id="markdown-toc">










<li><a href="index.html#before-you-begin">Before you begin</a></li>












<li><a href="index.html#choosing-a-page-type">Choosing a page type</a></li>




<li><a href="index.html#choosing-a-title-and-filename">Choosing a title and filename</a></li>




<li><a href="index.html#adding-the-topic-title-to-the-front-matter">Adding the topic title to the front matter</a></li>




<li><a href="index.html#choosing-a-directory">Choosing a directory</a></li>




<li><a href="index.html#creating-an-entry-in-the-table-of-contents">Creating an entry in the table of contents</a></li>




<li><a href="index.html#including-code-from-another-file">Including code from another file</a></li>




<li><a href="index.html#showing-how-to-create-an-api-object-from-a-configuration-file">Showing how to create an API object from a configuration file</a></li>




<li><a href="index.html#adding-images-to-a-topic">Adding images to a topic</a></li>




























<li><a href="index.html#what-s-next">What's next</a></li>



</ul>



<h2 id="before-you-begin">Before you begin</h2>
<p>Create a fork of the Kubernetes documentation repository as described in
<a href="../stage-documentation-changes/index.html">Creating a Documentation Pull Request</a>.</p>




<h2 id="choosing-a-page-type">Choosing a page type</h2>

<p>As you prepare to write a new topic, think about which of these page types
is the best fit for your content:</p>

<table>

  <tr>
    <td>Task</td>
    <td>A task page shows how to do a single thing. The idea is to give readers a sequence of steps that they can actually do as they read the page. A task page can be short or long, provided it stays focused on one area. In a task page, it is OK to blend brief explanations with the steps to be performed, but if you need to provide a lengthy explanation, you should do that in a concept topic. Related task and concept topics should link to each other. For an example of a short task page, see <a href="../../../tasks/configure-pod-container/configure-volume-storage/index.html">Configure a Pod to Use a Volume for Storage</a>. For an example of a longer task page, see <a href="../../../user-guide/liveness/index.html">Configure Liveness and Readiness Probes</a></td>
  </tr>

  <tr>
    <td>Tutorial</td>
    <td>A tutorial page shows how to accomplish a goal that ties together several Kubernetes features. A tutorial might provide several sequences of steps that readers can actually do as they read the page. Or it might provide explanations of related pieces of code. For example, a tutorial could provide a walkthrough of a code sample. A tutorial can include brief explanations of the Kubernetes features that are being tied together, but should link to related concept topics for deep explanations of individual features.</td>
  </tr>

  <tr>
    <td>Concept</td>
    <td>A concept page explains some aspect of Kubernetes. For example, a concept page might describe the Kubernetes Deployment object and explain the role it plays as an application is deployed, scaled, and updated. Typically, concept pages don't include sequences of steps, but instead provide links to tasks or tutorials. For an example of a concept topic, see <a href="../../../admin/node.1">Nodes</a>.</td>
  </tr>

</table>

<p>Each page type has a
<a href="../page-templates/index.html">template</a>
that you can use as you write your topic.
Using templates helps ensure consistency among topics of a given type.</p>

<h2 id="choosing-a-title-and-filename">Choosing a title and filename</h2>

<p>Choose a title that has the keywords you want search engines to find.
Create a filename that uses the words in your title separated by hyphens.
For example, the topic with title
<a href="../../../tasks/access-kubernetes-api/http-proxy-access-api.1">Using an HTTP Proxy to Access the Kubernetes API</a>
has filename <code>http-proxy-access-api.md</code>. You don&rsquo;t need to put
&ldquo;kubernetes&rdquo; in the filename, because &ldquo;kubernetes&rdquo; is already in the
URL for the topic, for example:</p>

<pre><code>   http://kubernetes.io/docs/tasks/access-kubernetes-api/http-proxy-access-api/
</code></pre>

<h2 id="adding-the-topic-title-to-the-front-matter">Adding the topic title to the front matter</h2>

<p>In your topic, put a <code>title</code> field in the
<a href="https://jekyllrb.com/docs/frontmatter/" target="_blank">front matter</a>.
The front matter is the YAML block that is between the
triple-dashed lines at the top of the page. Here&rsquo;s an example:</p>

<pre><code>---
title: Using an HTTP Proxy to Access the Kubernetes API
---
</code></pre>

<h2 id="choosing-a-directory">Choosing a directory</h2>

<p>Depending on your page type, put your new file in a subdirectory of one of these:</p>

<ul>
<li>/docs/tasks/</li>
<li>/docs/tutorials/</li>
<li>/docs/concepts/</li>
</ul>

<p>You can put your file in an existing subdirectory, or you can create a new
subdirectory.</p>

<h2 id="creating-an-entry-in-the-table-of-contents">Creating an entry in the table of contents</h2>

<p>Depending page type, create an entry in one of these files:</p>

<ul>
<li>/_data/tasks.yaml</li>
<li>/_data/tutorials.yaml</li>
<li>/_data/concepts.yaml</li>
</ul>

<p>Here&rsquo;s an example of an entry in /_data/tasks.yaml:</p>

<pre><code>- docs/tasks/configure-pod-container/configure-volume-storage.md
</code></pre>

<h2 id="including-code-from-another-file">Including code from another file</h2>

<p>To include a code file in your topic, place the code file in the Kubernetes
documentation repository, preferably in the same directory as your topic
file. In your topic file, use the <code>include</code> tag:</p>

<pre>&#123;% include code.html language="&lt;LEXERVALUE&gt;" file="&lt;RELATIVEPATH&gt;" ghlink="/&lt;PATHFROMROOT&gt;" %&#125;</pre>

<p>where:</p>

<ul>
<li><code>&lt;LEXERVALUE&gt;</code> is the language in which the file was written. This must be
<a href="https://github.com/jneen/rouge/wiki/list-of-supported-languages-and-lexers" target="_blank">a value supported by Rouge</a>.</li>
<li><code>&lt;RELATIVEPATH&gt;</code> is the path to the file you&rsquo;re including, relative to the current file, for example, <code>local-volume.yaml</code>.</li>
<li><code>&lt;PATHFROMROOT&gt;</code> is the path to the file relative to root, for example, <code>docs/tutorials/stateful-application/mysql-wordpress-persistent-volume/local-volumes.yaml</code>.</li>
</ul>

<p>Here&rsquo;s an example of using the <code>include</code> tag:</p>

<pre>&#123;% include code.html language="yaml" file="gce-volume.yaml" ghlink="/docs/tutorials/stateful-application/gce-volume.yaml" %&#125;</pre>

<h2 id="showing-how-to-create-an-api-object-from-a-configuration-file">Showing how to create an API object from a configuration file</h2>

<p>If you need to show the reader how to create an API object based on a
configuration file, place the configuration file in the Kubernetes documentation
repository, preferably in the same directory as your topic file.</p>

<p>In your topic, show this command:</p>

<pre><code>kubectl create -f https://k8s.io/&lt;PATHFROMROOT&gt;
</code></pre>

<p>where <code>&lt;PATHFROMROOT&gt;</code> is the path to the configuration file relative to root,
for example, <code>docs/tutorials/stateful-application/mysql-wordpress-persistent-volume/local-volumes.yaml</code>.</p>

<p>Here&rsquo;s an example of a command that creates an API object from a configuration file:</p>

<pre><code>kubectl create -f https://k8s.io/docs/tutorials/stateful-application/mysql-wordpress-persistent-volume/local-volumes.yaml
</code></pre>

<p>For an example of a topic that uses this technique, see
<a href="../../../tutorials/stateful-application/run-stateful-application/index.html">Running a Single-Instance Stateful Application</a>.</p>

<h2 id="adding-images-to-a-topic">Adding images to a topic</h2>

<p>Put image files in the <code>/images</code> directory. The preferred
image format is SVG.</p>

















<h2 id="what-s-next">What&#39;s next</h2>
<ul>
<li>Learn about <a href="../page-templates/index.html">using page templates</a>.</li>
<li>Learn about <a href="../stage-documentation-changes/index.html">staging your changes</a>.</li>
<li>Learn about <a href="../stage-documentation-changes/index.html">creating a pull request</a>.</li>
</ul>






				<div class="issue-button-container">
					<p><a href="index.html"><img src="https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/home/contribute/write-new-topic.md?pixel" alt="Analytics" /></a></p>
					
					
					<script type="text/javascript">
					PDRTJS_settings_8345992 = {
					"id" : "8345992",
					"unique_id" : "\/docs\/home\/contribute\/write-new-topic\/",
					"title" : "Writing a New Topic",
					"permalink" : "https:\/\/kubernetes.io\/docs\/home\/contribute\/write-new-topic\/"
					};
					(function(d,c,j){if(!document.getElementById(j)){var pd=d.createElement(c),s;pd.id=j;pd.src=('https:'==document.location.protocol)?'https://polldaddy.com/js/rating/rating.js':'http://i0.poll.fm/js/rating/rating.js';s=document.getElementsByTagName(c)[0];s.parentNode.insertBefore(pd,s);}}(document,'script','pd-rating-js'));
					</script>
					<a href="index.html" onclick="window.open('https://github.com/kubernetes/website/issues/new?title=Issue%20with%20' +
					'k8s.io'+window.location.pathname)" class="button issue">Create an Issue</a>
					
					
					
					<a href="../../../editdocs#docs/home/contribute/write-new-topic.md" class="button issue">Edit this Page</a>
					
				</div>
			</div>
		</section>
		<footer>
    <main class="light-text">
        <nav>
            
            
            
            <a href="../../../home.1">Documentation</a>
            
            <a href="../../../../blog/index.html">Blog</a>
            
            <a href="../../../../partners/index.html">Partners</a>
            
            <a href="../../../../community/index.html">Community</a>
            
            <a href="../../../../case-studies/index.html">Case Studies</a>
            
        </nav>
        <div class="social">
            <div>
                <a href="https://twitter.com/kubernetesio" class="twitter"><span>twitter</span></a>
                <a href="https://github.com/kubernetes/kubernetes" class="github"><span>Github</span></a>
                <a href="http://slack.k8s.io/" class="slack"><span>Slack</span></a>
            </div>
            <div>
                <a href="http://stackoverflow.com/questions/tagged/kubernetes" class="stack-overflow"><span>Stack Overflow</span></a>
                <a href="https://discuss.kubernetes.io" class="mailing-list"><span>Forum</span></a>
                <a href="https://calendar.google.com/calendar/embed?src=nt2tcnbtbied3l6gi2h29slvc0%40group.calendar.google.com" class="calendar"><span>Events Calendar</span></a>
            </div>
            <div>
                <a href="../../../getting-started-guides/index.html" class="button">Get Kubernetes</a>
                <a href="https://git.k8s.io/community/contributors/guide" class="button">Contribute</a>
            </div>
        </div>
        <div id="miceType" class="center">
            &copy; 2018 The Kubernetes Authors | Documentation Distributed under <a href="https://git.k8s.io/website/LICENSE" class="light-text">CC BY 4.0</a>
        </div>
        <div id="miceType" class="center">
            Copyright &copy; 2018 The Linux Foundation&reg;. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our <a href="https://www.linuxfoundation.org/trademark-usage" class="light-text">Trademark Usage page</a>
        </div>
    </main>
</footer>

		<button class="flyout-button" onclick="kub.toggleToc()"></button>

<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
    (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-36037335-10', 'auto');
ga('send', 'pageview');


(function () {
    window.addEventListener('DOMContentLoaded', init)

        
        function init() {
            window.removeEventListener('DOMContentLoaded', init)
                hideNav()
        }

    function hideNav(toc){
        if (!toc) toc = document.querySelector('#docsToc')
        if (!toc) return
            var container = toc.querySelector('.container')

                
                if (container) {
                    if (container.childElementCount === 0 || toc.querySelectorAll('a.item').length === 1) {
                        toc.style.display = 'none'
                            document.getElementById('docsContent').style.width = '100%'
                    }
                } else {
                    requestAnimationFrame(function () {
                        hideNav(toc)
                    })
                }
    }
})();
</script>



	</body>
</html>